home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr11 / gedvw105.zip / GEDVIEW.TXT < prev    next >
Text File  |  1995-03-05  |  13KB  |  315 lines
  1.  
  2.  
  3.                  GEDView 1.05 - Beta test release - 5 Mar 1995
  4.                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.  
  6.  
  7.                USAGE: GV [-n] <filename> [scriptname [argument]]
  8.  
  9.  
  10.  
  11.             The GEDCOM data format  was developed by the LDS Church as a
  12.        way to exchange genealogical data between two systems.
  13.  
  14.             GEDView does this:
  15.  
  16.                  * indexes, searches and displays GEDCOM database files,
  17.                    even large ones, very quickly,
  18.  
  19.                  * organizes each record into a readable format,
  20.  
  21.                  * easily accesses related records by tabbing to or
  22.                    clicking on a GEDCOM "pointer" in the current record,
  23.  
  24.                  * translates tag names (field names) into descriptive
  25.                    words or phrases.
  26.  
  27.                  * toggles between GEDCOM or "enhanced" display mode,
  28.  
  29.                  * saves or appends selected records to file in GEDCOM
  30.                    or "enhanced" style,
  31.  
  32.                  * has the facility to generate user-designed reports
  33.                    through its script command set,
  34.  
  35.                  * supports color monitors and a Microsoft mouse,
  36.  
  37.                  * accepts commands via pull-down menus, mouse buttons,
  38.                    textual prompt-style commands or scripts.
  39.  
  40.  
  41.        SPECIFICATIONS
  42.        ~~~~~~~~~~~~~~
  43.             I used the specifications for the proposed GEDCOM  standard,
  44.        draft release 5.3.
  45.  
  46.             Not  all  GEDCOM files are created equal.  In fact, some are
  47.        downright inferior.  For that reason, GEDView may not work on all
  48.        files purported to be GEDCOM.
  49.  
  50.             GEDView will handle
  51.  
  52.                  * files sizes up to 2 gigabytes and will read as many
  53.                    records as can be squeezed into that,
  54.  
  55.                  * records up to 32,000 bytes in length,
  56.  
  57.                  * scripts having up to 8,000 lines.
  58.  
  59.             GEDView was written to be fast.  It will  index  and  create
  60.        look-up  tables  at the rate of about 10 seconds per megabyte and
  61.        will do a global search  in about 8 seconds per each megabyte (as
  62.        performed by on my 386DX-33).
  63.  
  64.  
  65.        Please note the following
  66.        ~~~~~~~~~~~~~~~~~~~~~~~~~
  67.             Tag names that are not described by GEDCOM  draft  5.3,  are
  68.        displayed in caps, preceded by an asterisk (*).
  69.  
  70.             GEDView will create several new files for *each* GEDCOM file
  71.        that is read -- and they  are  not  deleted when the program ends
  72.        (the -n switch can be used on the command  line  to  suppress the
  73.        indexing of an already indexed file.) Be sure
  74.        there is plenty room on your disk.
  75.  
  76.  
  77.        WRITING SCRIPTS
  78.        ~~~~~~~~~~~~~~~
  79.             I have a text editor in the works and will make it available
  80.        in a future release.   In  the  meantime,  GEDView scripts can be
  81.        written using any editor or word processor  -SAVED  AS  AN  ASCII
  82.        FILE.
  83.  
  84.             GEDView  does  very little syntax error checking. And I have
  85.        done little to discover  the  results  of  bad  code.   For  that
  86.        reason,  I  must  insist on the standard disclaimer.*   The  best
  87.        advice  I  can give right now is to be careful.  A poorly-written
  88.        script, can cause any  number  of "undefined" conditions, such as
  89.        freezing your system.
  90.  
  91.             Although the basic core or engine of GEDView  is  very  fast
  92.        and  efficient, its scripting capability is _very_ slow and needs
  93.        more work.  And, although  the  script  command  set  is  greatly
  94.        expanded  in  this  version,  it  is  still   rather  clunky  and
  95.        simplistic.
  96.  
  97.             A script  name  and its argument may be specified at the DOS
  98.        command line:
  99.  
  100.                       GV -n SAMPLE.GED INDENT.PRG SAMPLE2.GED
  101.  
  102.             That command will start GEDView, will not index (because the
  103.        -n  switch is used -- an accurate index is  presumably  known  to
  104.        exist) and will start up the script INDENT.PRG.  The output file,
  105.        SAMPLE2.GED, will be  created.  The  program can be automatically
  106.        terminated by including the GEDView command, QUIT.
  107.  
  108.             The script commands are found in the Help menu.
  109.  
  110.                 * Always conclude your script with an END statement.
  111.  
  112.                 * The resulting <action> of an IF statement must go
  113.                   on the next line.
  114.  
  115.                 * Do not call a script from within another.
  116.  
  117.                 * GOSUBs can be nested, DO-REPEATs cannot be nested.
  118.  
  119.                 * Variable names ($ARG, $FULLNAME, $COUNTER, etc.) must
  120.                   be capped.  Otherwise, case does not matter.
  121.  
  122.                 * The  system must have sufficient memory resources  for
  123.                   the  system  command.   The DOS sort, for instance, in
  124.                   SDX.PRG will easily fail.
  125.  
  126.  
  127.        Return Values
  128.        ~~~~~~~~~~~~~
  129.             Most GEDView functions will return a value. The FAILED value
  130.        can be thought as being 0, no, negative, unsuccessful, not equal,
  131.        etc.  The  EQUAL  value  can  be  thought of as yes, 1, positive,
  132.        successful, etc.
  133.  
  134.             If a GEDView command  is  not successful, the FAILED flag is
  135.        set. --  An  IFFAILED  will  check  the  status  of  the  command
  136.        IMMEDIATELY preceding it.  Therefore, nothing, not even a
  137.        GOTO,  comment  or  a  label  can come between the two lines (the
  138.        command to be checked and the IFFAILED).
  139.  
  140.             Failed (0) and equal (1) can be returned from a GOSUB as
  141.        an argument of the RETURN statement:
  142.  
  143.                       RETURN 1
  144.  
  145.             Below is the INDENT.PRG  sample  script.  To invoke it, type
  146.        RUN INDENT.PRG at the dot prompt or select  Run  Script  from the
  147.        Reports  Menu.   An  output  file name may also be included. If a
  148.        file name has not been  given,  INDENT.PRG will create a new copy
  149.        of the opened GEDCOM file with the name NEW.GED.   Each line will
  150.        be  indented by 2 spaces times the line's level.  For instance, a
  151.        level 2 line will be indented by four spaces.
  152.  
  153.             If your program is recursive  -- that is, returns to the top
  154.        over and over -- you must check for a failed condition to end the
  155.        execution.  Otherwise,  you  will  be stuck in an "infinite loop"
  156.        and will probably have to reboot your system.
  157.  
  158.             Remember,  GEDCOM files  can  be  very  different  from  one
  159.        another.  Because a script may work for one GEDCOM  it  will  not
  160.        necessarily work for another.
  161.  
  162.        --
  163.  
  164.             set bell off
  165.             remember record
  166.             compare $ARG
  167.             ifequal
  168.                     goto set-default-name
  169.             set #outfile $ARG
  170.             save $OUTFILE ""
  171.             go 1
  172.  
  173.             :the-top
  174.                     show creating $OUTFILE ....
  175.                     get line
  176.                     iffailed
  177.                             goto the-end
  178.  
  179.             :do-record
  180.                     set #counter -1
  181.                     gosub check-level
  182.                     append $OUTFILE $LINE
  183.                     append $OUTFILE "\J"
  184.                     get next line
  185.                     ifequal
  186.                             goto do-record
  187.                     next
  188.                     iffailed
  189.                             goto the-end
  190.                     goto the-top
  191.  
  192.             :the-end
  193.                     go record
  194.                     set bell on
  195.                     end
  196.  
  197.             :check-level
  198.                     add 1 #counter
  199.                     ifescape
  200.                             goto the-end
  201.                     compare $FIELD1 $COUNTER
  202.                     iffailed
  203.                             goto check-level
  204.                     do $COUNTER
  205.                             append $OUTFILE "  "
  206.                     repeat
  207.                     return
  208.  
  209.             :set-default-name
  210.                     set #outfile new.ged
  211.                     save $OUTFILE
  212.                     go 1
  213.                     goto the-top
  214.  
  215.  
  216.             These scripts are included in this release.  They are
  217.        simple   examples   intended   only   to   illustrate   GEDView's
  218.        capabilities. Improvements will be  included  in  future releases
  219.        and/or   archived  in  a  presently-undetermined   directory   at
  220.        genealogy.emcee.com.  I'll be happy to include additional scripts
  221.        of merit in my FTP site.
  222.  
  223.  
  224.                       AHNEN.PRG creates ahnentafel for INDI
  225.                       FATHER.PRG displays father of INDI
  226.                       FGS.PRG creates Group Sheet for FAM
  227.                       FLINE.PRG displays earliest paternal ancestor
  228.                                 for INDI
  229.                       HTML.PRG creates Web page for FAM
  230.                       INDENT.PRG  <arg>  created  indented  GEDCOM  file
  231.                       MOTHER.PRG displays mother of INDI
  232.                       SAVE-ALL.PRG  creates  file  in  'enhanced' format
  233.                       SDX.PRG   creates   and   sorts   Soundex   report
  234.                       SEARCH.PRG <arg> creates file of records with
  235.                                 matching argument
  236.  
  237.  
  238.        UPCOMING RELEASES
  239.        ~~~~~~~~~~~~~~~~~
  240.             The basic plan for GEDView is to keep it small and fast
  241.        but to give it the capability for virtually unlimited flexibility
  242.        through scripting and other features.
  243.  
  244.             These three points will be at the top of the list:
  245.  
  246.                  * Further improve the core speed.
  247.  
  248.                  * Greatly increase GEDView's script performance and
  249.                    enhance the command set.
  250.  
  251.                  * Fix bugs.
  252.  
  253.                  * Improve the doc.
  254.  
  255.                  * Internal sort.
  256.  
  257.             Some intended features include:
  258.  
  259.                  * Pop-up directory listing.
  260.  
  261.                  * Configurable default data directory.
  262.  
  263.                  * Hot-key definitions and macros.
  264.  
  265.  
  266.        RELEASE HISTORY
  267.        ~~~~~~~~~~~~~~~
  268.             1.00 - 4/8/94
  269.                    Early unofficial pre-beta in limited circulation.
  270.             1.01 - 7/5/94 First beta release.
  271.                    Added keys to Viewer
  272.                    Redesigned buttons
  273.                    Incl command SET PRINT
  274.                    Added help button
  275.             1.02 - 7/20/94
  276.                    Revised to update FAT table after file creation.
  277.             1.03 - 8/3/94
  278.                    Fixed F10/Next freeze-up.
  279.             1.04 - 8/24/94
  280.                    Another freeze-up fix.
  281.                    Fixed  script  command  IF  FAILED for NEXT  /  PREV.
  282.                    Modified "formatted" mode for save.
  283.                    Fixed SET EOL command.
  284.             1.05 - 2/24/95
  285.                    Clears screen when terminated.
  286.                    Changed  Save  /  Append  hotkeys  to  F4 and alt-F4.
  287.                    Search is no longer case sensitive.
  288.                    Many bugs fixed.
  289.                    Several new script commands.
  290.                    IF FAILED changed to IFFAILED.
  291.                    REMEMBER $RECORD changed to REMEMBER RECORD.
  292.  
  293.  
  294.  
  295.             I have  made many changes  in  the  last  couple  of  weeks,
  296.        particularly relating to scripting.  There has not been much
  297.        time  to  thoroughly  test  the  results.   Undoubtedly,  various
  298.        situations  will arise that had not as yet been contemplated.  It
  299.        will be a big help to  me to have any and all bugs reported to me
  300.        via email.
  301.  
  302.        Michael Cooley, Mar 1995
  303.        email: michael@emcee.com
  304.  
  305.        * This  version  of GEDView is neither commercial  nor  shareware
  306.        software  but  is  freely distributed under the terms, conditions
  307.        and understanding of the following: GEDView is still in the early
  308.        stages of development and has been tested  on  only one machine -
  309.        mine.  Any  number  of  conditions can be present - including the
  310.        manufacture of equipment  and  the  operators  mood  -- which can
  311.        influence the performance of this program.   Therefore, I bear no
  312.        responsibility  for  loss  of  data  or  damage  to  equipment or
  313.        operator's personality  resulting  from the use of GEDView and/or
  314.        its by-products.  The user uses at his/her own risk.
  315.